home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / SCSL / dgeevx.z / dgeevx
Encoding:
Text File  |  2002-10-03  |  10.9 KB  |  265 lines
  1.  
  2.  
  3.  
  4. DDDDGGGGEEEEEEEEVVVVXXXX((((3333SSSS))))                                                          DDDDGGGGEEEEEEEEVVVVXXXX((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      DGEEVX - compute for an N-by-N real nonsymmetric matrix A, the
  10.      eigenvalues and, optionally, the left and/or right eigenvectors
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      SUBROUTINE DGEEVX( BALANC, JOBVL, JOBVR, SENSE, N, A, LDA, WR, WI, VL,
  14.                         LDVL, VR, LDVR, ILO, IHI, SCALE, ABNRM, RCONDE,
  15.                         RCONDV, WORK, LWORK, IWORK, INFO )
  16.  
  17.          CHARACTER      BALANC, JOBVL, JOBVR, SENSE
  18.  
  19.          INTEGER        IHI, ILO, INFO, LDA, LDVL, LDVR, LWORK, N
  20.  
  21.          DOUBLE         PRECISION ABNRM
  22.  
  23.          INTEGER        IWORK( * )
  24.  
  25.          DOUBLE         PRECISION A( LDA, * ), RCONDE( * ), RCONDV( * ),
  26.                         SCALE( * ), VL( LDVL, * ), VR( LDVR, * ), WI( * ),
  27.                         WORK( * ), WR( * )
  28.  
  29. IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
  30.      These routines are part of the SCSL Scientific Library and can be loaded
  31.      using either the -lscs or the -lscs_mp option.  The -lscs_mp option
  32.      directs the linker to use the multi-processor version of the library.
  33.  
  34.      When linking to SCSL with -lscs or -lscs_mp, the default integer size is
  35.      4 bytes (32 bits). Another version of SCSL is available in which integers
  36.      are 8 bytes (64 bits).  This version allows the user access to larger
  37.      memory sizes and helps when porting legacy Cray codes.  It can be loaded
  38.      by using the -lscs_i8 option or the -lscs_i8_mp option. A program may use
  39.      only one of the two versions; 4-byte integer and 8-byte integer library
  40.      calls cannot be mixed.
  41.  
  42. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  43.      DGEEVX computes for an N-by-N real nonsymmetric matrix A, the eigenvalues
  44.      and, optionally, the left and/or right eigenvectors. Optionally also, it
  45.      computes a balancing transformation to improve the conditioning of the
  46.      eigenvalues and eigenvectors (ILO, IHI, SCALE, and ABNRM), reciprocal
  47.      condition numbers for the eigenvalues (RCONDE), and reciprocal condition
  48.      numbers for the right
  49.      eigenvectors (RCONDV).
  50.  
  51.      The right eigenvector v(j) of A satisfies
  52.                       A * v(j) = lambda(j) * v(j)
  53.      where lambda(j) is its eigenvalue.
  54.      The left eigenvector u(j) of A satisfies
  55.                    u(j)**H * A = lambda(j) * u(j)**H
  56.      where u(j)**H denotes the conjugate transpose of u(j).
  57.  
  58.      The computed eigenvectors are normalized to have Euclidean norm equal to
  59.      1 and largest component real.
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. DDDDGGGGEEEEEEEEVVVVXXXX((((3333SSSS))))                                                          DDDDGGGGEEEEEEEEVVVVXXXX((((3333SSSS))))
  71.  
  72.  
  73.  
  74.      Balancing a matrix means permuting the rows and columns to make it more
  75.      nearly upper triangular, and applying a diagonal similarity
  76.      transformation D * A * D**(-1), where D is a diagonal matrix, to make its
  77.      rows and columns closer in norm and the condition numbers of its
  78.      eigenvalues and eigenvectors smaller.  The computed reciprocal condition
  79.      numbers correspond to the balanced matrix.  Permuting rows and columns
  80.      will not change the condition numbers (in exact arithmetic) but diagonal
  81.      scaling will.  For further explanation of balancing, see section 4.10.2
  82.      of the LAPACK Users' Guide.
  83.  
  84.  
  85. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  86.      BALANC  (input) CHARACTER*1
  87.              Indicates how the input matrix should be diagonally scaled and/or
  88.              permuted to improve the conditioning of its eigenvalues.  = 'N':
  89.              Do not diagonally scale or permute;
  90.              = 'P': Perform permutations to make the matrix more nearly upper
  91.              triangular. Do not diagonally scale; = 'S': Diagonally scale the
  92.              matrix, i.e. replace A by D*A*D**(-1), where D is a diagonal
  93.              matrix chosen to make the rows and columns of A more equal in
  94.              norm. Do not permute; = 'B': Both diagonally scale and permute A.
  95.  
  96.              Computed reciprocal condition numbers will be for the matrix
  97.              after balancing and/or permuting. Permuting does not change
  98.              condition numbers (in exact arithmetic), but balancing does.
  99.  
  100.      JOBVL   (input) CHARACTER*1
  101.              = 'N': left eigenvectors of A are not computed;
  102.              = 'V': left eigenvectors of A are computed.  If SENSE = 'E' or
  103.              'B', JOBVL must = 'V'.
  104.  
  105.      JOBVR   (input) CHARACTER*1
  106.              = 'N': right eigenvectors of A are not computed;
  107.              = 'V': right eigenvectors of A are computed.  If SENSE = 'E' or
  108.              'B', JOBVR must = 'V'.
  109.  
  110.      SENSE   (input) CHARACTER*1
  111.              Determines which reciprocal condition numbers are computed.  =
  112.              'N': None are computed;
  113.              = 'E': Computed for eigenvalues only;
  114.              = 'V': Computed for right eigenvectors only;
  115.              = 'B': Computed for eigenvalues and right eigenvectors.
  116.  
  117.              If SENSE = 'E' or 'B', both left and right eigenvectors must also
  118.              be computed (JOBVL = 'V' and JOBVR = 'V').
  119.  
  120.      N       (input) INTEGER
  121.              The order of the matrix A. N >= 0.
  122.  
  123.      A       (input/output) DOUBLE PRECISION array, dimension (LDA,N)
  124.              On entry, the N-by-N matrix A.  On exit, A has been overwritten.
  125.              If JOBVL = 'V' or JOBVR = 'V', A contains the real Schur form of
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. DDDDGGGGEEEEEEEEVVVVXXXX((((3333SSSS))))                                                          DDDDGGGGEEEEEEEEVVVVXXXX((((3333SSSS))))
  137.  
  138.  
  139.  
  140.              the balanced version of the input matrix A.
  141.  
  142.      LDA     (input) INTEGER
  143.              The leading dimension of the array A.  LDA >= max(1,N).
  144.  
  145.      WR      (output) DOUBLE PRECISION array, dimension (N)
  146.              WI      (output) DOUBLE PRECISION array, dimension (N) WR and WI
  147.              contain the real and imaginary parts, respectively, of the
  148.              computed eigenvalues.  Complex conjugate pairs of eigenvalues
  149.              will appear consecutively with the eigenvalue having the positive
  150.              imaginary part first.
  151.  
  152.      VL      (output) DOUBLE PRECISION array, dimension (LDVL,N)
  153.              If JOBVL = 'V', the left eigenvectors u(j) are stored one after
  154.              another in the columns of VL, in the same order as their
  155.              eigenvalues.  If JOBVL = 'N', VL is not referenced.  If the j-th
  156.              eigenvalue is real, then u(j) = VL(:,j), the j-th column of VL.
  157.              If the j-th and (j+1)-st eigenvalues form a complex conjugate
  158.              pair, then u(j) = VL(:,j) + i*VL(:,j+1) and
  159.              u(j+1) = VL(:,j) - i*VL(:,j+1).
  160.  
  161.      LDVL    (input) INTEGER
  162.              The leading dimension of the array VL.  LDVL >= 1; if JOBVL =
  163.              'V', LDVL >= N.
  164.  
  165.      VR      (output) DOUBLE PRECISION array, dimension (LDVR,N)
  166.              If JOBVR = 'V', the right eigenvectors v(j) are stored one after
  167.              another in the columns of VR, in the same order as their
  168.              eigenvalues.  If JOBVR = 'N', VR is not referenced.  If the j-th
  169.              eigenvalue is real, then v(j) = VR(:,j), the j-th column of VR.
  170.              If the j-th and (j+1)-st eigenvalues form a complex conjugate
  171.              pair, then v(j) = VR(:,j) + i*VR(:,j+1) and
  172.              v(j+1) = VR(:,j) - i*VR(:,j+1).
  173.  
  174.      LDVR    (input) INTEGER
  175.              The leading dimension of the array VR.  LDVR >= 1, and if JOBVR =
  176.              'V', LDVR >= N.
  177.  
  178.              ILO,IHI (output) INTEGER ILO and IHI are integer values
  179.              determined when A was balanced.  The balanced A(i,j) = 0 if I > J
  180.              and J = 1,...,ILO-1 or I = IHI+1,...,N.
  181.  
  182.      SCALE   (output) DOUBLE PRECISION array, dimension (N)
  183.              Details of the permutations and scaling factors applied when
  184.              balancing A.  If P(j) is the index of the row and column
  185.              interchanged with row and column j, and D(j) is the scaling
  186.              factor applied to row and column j, then SCALE(J) = P(J),    for
  187.              J = 1,...,ILO-1 = D(J),    for J = ILO,...,IHI = P(J)     for J =
  188.              IHI+1,...,N.  The order in which the interchanges are made is N
  189.              to IHI+1, then 1 to ILO-1.
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. DDDDGGGGEEEEEEEEVVVVXXXX((((3333SSSS))))                                                          DDDDGGGGEEEEEEEEVVVVXXXX((((3333SSSS))))
  203.  
  204.  
  205.  
  206.      ABNRM   (output) DOUBLE PRECISION
  207.              The one-norm of the balanced matrix (the maximum of the sum of
  208.              absolute values of elements of any column).
  209.  
  210.      RCONDE  (output) DOUBLE PRECISION array, dimension (N)
  211.              RCONDE(j) is the reciprocal condition number of the j-th
  212.              eigenvalue.
  213.  
  214.      RCONDV  (output) DOUBLE PRECISION array, dimension (N)
  215.              RCONDV(j) is the reciprocal condition number of the j-th right
  216.              eigenvector.
  217.  
  218.      WORK    (workspace/output) DOUBLE PRECISION array, dimension (LWORK)
  219.              On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
  220.  
  221.      LWORK   (input) INTEGER
  222.              The dimension of the array WORK.   If SENSE = 'N' or 'E', LWORK
  223.              >= max(1,2*N), and if JOBVL = 'V' or JOBVR = 'V', LWORK >= 3*N.
  224.              If SENSE = 'V' or 'B', LWORK >= N*(N+6).  For good performance,
  225.              LWORK must generally be larger.
  226.  
  227.              If LWORK = -1, then a workspace query is assumed; the routine
  228.              only calculates the optimal size of the WORK array, returns this
  229.              value as the first entry of the WORK array, and no error message
  230.              related to LWORK is issued by XERBLA.
  231.  
  232.      IWORK   (workspace) INTEGER array, dimension (2*N-2)
  233.              If SENSE = 'N' or 'E', not referenced.
  234.  
  235.      INFO    (output) INTEGER
  236.              = 0:  successful exit
  237.              < 0:  if INFO = -i, the i-th argument had an illegal value.
  238.              > 0:  if INFO = i, the QR algorithm failed to compute all the
  239.              eigenvalues, and no eigenvectors or condition numbers have been
  240.              computed; elements 1:ILO-1 and i+1:N of WR and WI contain
  241.              eigenvalues which have converged.
  242.  
  243. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  244.      INTRO_LAPACK(3S), INTRO_SCSL(3S)
  245.  
  246.      This man page is available only online.
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.